home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / clang / clint156.zip / README < prev    next >
Text File  |  1992-12-21  |  52KB  |  1,524 lines
  1.  
  2.                                   CLINT V1.56
  3.                                   ───────────
  4.       
  5.                       The Ultimate C Source Checking Tool
  6.       
  7.                  (c) 1992 R&D Associates - All Rights Reserved
  8.       
  9.           ┌──────────────────────────────────────────────────────────┐
  10.           │                                                          │
  11.           │       R&D Associates, 356 D. W. Highway Suite 232,       │
  12.           │                Merrimack, NH 03054, USA                  │
  13.           │                                                          │
  14.           │         R&D Associates, 16 High Street, Rainham,         │
  15.           │                   Kent ME8 7JE, ENGLAND                  │
  16.           │                                                          │
  17.           ├──────────────────────────────────────────────────────────┤
  18.           │                                                          │
  19.           │             R&D Associates can be contacted on           │
  20.           │                COMPUSERVE by mailing user ID:            │
  21.           │                                                          │
  22.           │                     100013,1042 (USA)                    │
  23.           │                   100111,1162 (Europe)                   │
  24.           │                                                          │
  25.           └──────────────────────────────────────────────────────────┘
  26.       
  27.                                  WHAT IS CLINT?
  28.                                  ──────────────
  29.       
  30.      CLint  is a tool which reads the  source files of your C programs, and
  31.      generates  reports about possible problems. As  it can look at ALL the
  32.      files  in a program, it is able to report far more than any C compiler
  33.      can.  Use CLint while developing your  programs, and you'll be assured
  34.      of type safe linkage, efficient code, and excellent portability.
  35.       
  36.      This  version of CLint  is released as SHAREWARE.  This means that you
  37.      use  it on a  try-before-you-buy basis. If you  find CLint useful, you
  38.      must  register within 30 days. We'll then send you the latest version,
  39.      with  more  documentation,  and  you'll receive  news  of  updates and
  40.      technical support. R&D Associates regrets that it is unable to provide
  41.      any  support for it's shareware  products without registration. Please
  42.      read the file LICENSE.DOC for more details.
  43.       
  44.      CLint  understands all  the industry  standard extensions  to the ANSI
  45.      standard  such as near, far,  huge, cdecl, pascal, asm,  and so on for
  46.      all  the supported compilers. It  understands and supports the Borland
  47.      psuedo registers, and segment types, and the Microsoft special segment
  48.      control extensions.
  49.       
  50.      A  special  feature  of CLint  is  that  it does  not  support models.
  51.      Instead, all type modifiers are unique, that is:
  52.       
  53.           char *    char far *          char near *    char huge *
  54.       
  55.  
  56.  
  57.  
  58.  
  59.                                     Page - 1
  60.  
  61.  
  62.  
  63.      and  all variations are considered unique pointer types. The advantage
  64.      is  that regardless  of the  model you use  for any  project, if CLint
  65.      produces  no warnings, then  you can safely change  models with no ill
  66.      effects.  At the same  time, it understands that  near pointers may be
  67.      converted  to far or huge  by default. For those  of you that have had
  68.      problems with mixed model programming, this feature alone will justify
  69.      your purchase!
  70.       
  71.      Clint  costs just  US$35 in the  USA or Canada,  and £19 in  the UK or
  72.      Europe.  Register today for an easier programming life. Please use the
  73.      enclosed file ORDER.DOC.
  74.       
  75.                             **** UPDATE RECORD ****
  76.                             ───────────────────────
  77.       
  78.      Version  1.41  added '-x'  switch which  releases  50K more  memory to
  79.      CLint,  but makes  checking fractionally slower.  Great for BorlandC++
  80.      with Windows!
  81.       
  82.      Versions 1.42 - 1.44, fixed some minor bugs concerning the handling of
  83.      prototypes  with  the 'register'  keyword,  and improved  detection of
  84.      illegal initialisations.
  85.       
  86.      Version  1.45 fixed some previously fatal error reports when extremely
  87.      outrageous syntax was used.
  88.       
  89.      Version  1.46 fixed 'UL' constant modifier error and a couple of minor
  90.      I/O irritations.
  91.       
  92.      Version  1.47 fixed  upper/lower case problem  in library redefinition
  93.      warning,  added '_asm'  and '_segname'  keywords for  MSC users, added
  94.      '-wlib' and '-w-lib' switches to enable/disable warnings about library
  95.      symbol redefinition.
  96.       
  97.      Version  1.50: Major  Upgrade. Replaced  SETUP.EXE with  a menu driven
  98.      program  CSETUP.EXE which  allows CLINT.CFG  to be  edited rather than
  99.      replaced  when  options  are  changed,  and  also  automatically edits
  100.      AUTOEXEC.BAT  if you  allow it. Added  the ability to  be invoked from
  101.      inside  the Borland IDE, with reports collected and usable by the IDE.
  102.      Added   indirect  files  with   .CLN  extension,  allowing  convenient
  103.      specification of collections of files for projects.
  104.       
  105.      Added  support for  the Intel iC96  compiler, and  other compilers for
  106.      micro  controllers which use the syntax  'extern register' for the on-
  107.      board I/O registers.
  108.       
  109.      Added support for Borland C++ 3.1 and it's massive runtime library.
  110.       
  111.      Added  the '-u'  switch to supress  messages when  partial programs or
  112.      libraries are examined.
  113.       
  114.      Added  the '-T'  switch to request  that Clint  reccomend variables or
  115.      functions which could be static.
  116.       
  117.  
  118.  
  119.  
  120.                                     Page - 2
  121.  
  122.  
  123.  
  124.      Added the '-E' switch to use CLint as a full ANSI preprocessor.
  125.       
  126.      Version  1.51 -  1.52 fixed a  couple of minor  errors, fixed address,
  127.      corrected non-ANSI handling of labels.
  128.       
  129.      Version 1.53: added support for the Intel iC86 compiler, the Microsoft
  130.      C++ 7.0 compiler, and the Microsoft QuickC for Windows compiler. Added
  131.      '-w-lnf'  to allow bit  fields longer than 16  bits. Major re-write of
  132.      the manual to include all the new features.
  133.       
  134.      Version  1.54: fixed a  problem when the  last line of  a file did not
  135.      have a line feed.
  136.       
  137.      Version 1.55: fixed a problem with #else after #elif.
  138.       
  139.      Version  1.56: Added support  for the Archimedes  68HC11 compiler, and
  140.      the  Mix PowerC compiler. Also fixed a problem with functions taking a
  141.      pointer-to-function  with  no  arguments. Added  support  for #message
  142.      which has the syntax:
  143.       
  144.           #message any_string
  145.       
  146.      and   prints  the  string.  Very   useful  for  debugging  conditional
  147.      compilations, but not supported by all compilers.
  148.       
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.                                     Page - 3
  182.  
  183.  
  184.  
  185.                                   INSTALLATION
  186.                                   ────────────
  187.       
  188.      Clint  shareware may  be downloaded  from bulletin  boards as  a self-
  189.      extracting  archive, or  on a floppy  disk from  shareware vendors. If
  190.      downloaded,  you must create  a directory (we  suggest C:\CLINT), copy
  191.      the  downloaded file  there, then execute  it, then  execute CSETUP to
  192.      complete the configuration.
  193.       
  194.      To install from a floppy insert the supplied CLint disk in a drive (we
  195.      assume drive A: here), then type:
  196.       
  197.           A:
  198.           CSETUP
  199.       
  200.      CSETUP  now  has an  easy to  use menu  interface. Specify  the target
  201.      directory,  select the compiler  you're using, and  specify where your
  202.      compiler lives. CSETUP fully supports your mouse, and has full on-line
  203.      context sensitive help. It writes (or updates if already existing) the
  204.      CLINT.CFG  file  according  to  your  choices,  renaming  any existing
  205.      CLINT.CFG  file as CLINTOLD.CFG. You can  use CSETUP again at any time
  206.      to change your choices.
  207.       
  208.      CSETUP  will automatically update your  AUTOEXEC.BAT file if required.
  209.      You  may  refuse CSETUP  permission to  change it,  in which  case you
  210.      should add the line:
  211.       
  212.           SET CLINT=C:\CLINT
  213.       
  214.      or similar if you installed to a different directory, and add CLint's
  215.      directory to your path.
  216.       
  217.      If  you use a ram disk, CLint will  run faster if you tell it to place
  218.      its  temporary files on ram disk. Assuming  you have a ram disk called
  219.      D: then add to the following line to your AUTOEXEC.BAT file:
  220.       
  221.           SET TMP=D: (or E: etc.)
  222.      or
  223.           SET TEMP=D:
  224.       
  225.                WARNING:  Don't specify  a nonexistent  name here,  or CLint
  226.                won't work!
  227.       
  228.      If  CSETUP modifies your AUTOEXEC.BAT, it  will reboot the computer to
  229.      allow  the changes  to take effect.  If instead you  manually make the
  230.      changes, you will need to re-boot.
  231.       
  232.                PLEASE  NOTE: If you change your  version of C you will need
  233.                to run CSETUP again when you make the change.
  234.       
  235.      For the Shareware version only, you must complete your installation by
  236.      executing  the batch file corresponding  to your chosen compiler. This
  237.      will  construct in your  CLint directory the  library file required to
  238.      check all uses of your compiler's runtime library.
  239.  
  240.  
  241.  
  242.                                     Page - 4
  243.  
  244.  
  245.  
  246.                                CONFIGURING CLINT
  247.                                ─────────────────
  248.       
  249.      You  can configure CLint  to your personal  preferences by editing the
  250.      supplied  CLINT.CFG file  which looks  like this  (varies according to
  251.      what you told CSETUP when CLint was installed):
  252.       
  253.           # (c) R&D Associates 1992.
  254.           # CLINT.CFG
  255.           -IC:\TC\INCLUDE         # TurboC++ 1.0
  256.           -lC:\CLINTREG\CTCPP10   # Clint Library for TurboC++ 1.0
  257.           #
  258.           # Add additional include directories with -I
  259.           # Add your Clint library directory with -l
  260.           # Add your common Clint warning switches:
  261.           # -wxxx to enable warning xxx,
  262.           # -w-xxx to disable warning xxx.
  263.           #
  264.       
  265.      As you will see later, you can add any of CLint's options to this file
  266.      as  you see  fit. The  '-I' line specifies  the name  of the directory
  267.      where  your compiler's header files are  - change this as required, or
  268.      use  CSETUP.  The  '-l'  line specifies  where  you  keep  the library
  269.      definitions, and the name of the definition file. If you use CSETUP to
  270.      change   your  CLint  configuration,  it  edits  your  CLINT.CFG  file
  271.      retaining all the information that did not need to be changed.
  272.       
  273.            ─────────────────────────────────────────────────────────
  274.            NOTE: You MUST specify complete pathnames with -I and -l!
  275.            ─────────────────────────────────────────────────────────
  276.       
  277.      CLint  searches for  CLINT.CFG in the  current directory,  then in the
  278.      directory  specified  in  the CLINT  environment  (SET)  variable. You
  279.      should  set up  the standard  CLINT.CFG file  to reflect  your general
  280.      needs.  If a special case arises in  one of your programs, simply copy
  281.      CLINT.CFG to that directory:
  282.       
  283.           CD MYDIR
  284.           COPY \CLINT\CLINT.CFG
  285.       
  286.      and edit it as required. No other use of CLint will be affected. CLint
  287.      expects  that each  line in CLINT.CFG  is a CLint  option which starts
  288.      with  '-' and is followed by an  option letter, and any required text.
  289.      Any  number of  other lines  may be  present in  the file  and will be
  290.      ignored. You can also comment any line by using '#' like this:
  291.       
  292.           -l\clint\cbcpp30    # BorlandC++ 3.0
  293.       
  294.      Such comments are ignored. CLint is insensitive to case in the command
  295.      line or in CLINT.CFG except as detailed later.
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.                                     Page - 5
  304.  
  305.  
  306.  
  307.                                   USING CLINT
  308.                                   ───────────
  309.       
  310.      In the simplest case, you will use CLint like this:
  311.       
  312.           CLINT *.C
  313.       
  314.      CLint  will read all of the  source files, analyse them carefully, and
  315.      report on any possibly problems, ANSI violations, portability problems
  316.      and  so forth. It assumes that all the files specified are part of one
  317.      program,  and will  be linked together,  and linked  with the run-time
  318.      library  routines specified in  CLINT.CFG or with  '-l' options on the
  319.      command line.
  320.       
  321.      It  checks carefully  that symbols  declared in  one file  and used in
  322.      another  have the same  declaration in both  files; that all functions
  323.      defined  are actually called; that all  variables defined are used. If
  324.      CLint  produces no  warnings or errors  about such things,  you can be
  325.      assured that the program when linked is type-safe.
  326.       
  327.      There may be cases where you have run-time libraries supplied by other
  328.      vendors,  or written  by yourself. You  will need to  tell CLint about
  329.      them  to obtain full checking. If you don't, CLint will complain about
  330.      symbols which are never defined.
  331.       
  332.      Let's assume that you have a library called MYLIB in \MYLIB, which has
  333.      a  header MYLIB.H. The first  thing to do is  verify that there are no
  334.      errors in MYLIB:
  335.       
  336.           CD \MYLIB
  337.           CLINT *.C -u
  338.       
  339.      Fix any errors reported before proceeding! Then you do:
  340.       
  341.           CLINT MYLIB.H -L MYLIBDEF
  342.       
  343.      And finally you add the line:
  344.       
  345.           -l\MYLIB\MYLIBDEF
  346.       
  347.      to  CLINT.CFG. (If you  don't want to  add this line,  simply type the
  348.      '-l' option when you run CLint.)
  349.       
  350.      The really important options you may need to use are:
  351.       
  352.           -Dname=value   define a preprocessor macro
  353.           -Uname         undefine a preprocessor macro
  354.           -lfile         specify a CLint library file to check against
  355.       
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.                                     Page - 6
  365.  
  366.  
  367.  
  368.      When   reading  header  files,   CLint  distinguishes  between  header
  369.      directories specified in CLINT.CFG, and those specified in the command
  370.      line.  The former  are assumed to  be your compiler  or library header
  371.      files, the latter header files which are part of the program.
  372.       
  373.      This  is  only  important  when '-w-shd'  is  used  (don't  warn about
  374.      compiler headers - the default), as CLint will only be silent on minor
  375.      problems in compiler headers - not program ones.
  376.       
  377.      The search order for headers which use "file.h" is:
  378.       
  379.           1) Current directory,
  380.       
  381.           2) Directories given in -I in the command,
  382.       
  383.           3) Directories given in -I in CLINT.CFG.
  384.       
  385.      For headers which use <file.h> only (2) and (3) are searched.
  386.       
  387.      The  built-in preprocessor is  a full ANSI  implementation. It defines
  388.      the required preprocessor macros:
  389.       
  390.           __LINE__, __FILE_, __DATE__, __TIME__
  391.       
  392.      and also the macros
  393.       
  394.           __DOS__ and __CLINT__
  395.       
  396.      with  the value '1'. If you require __STDC__ place '-D__STDC__' on the
  397.      command line or in CLINT.CFG.
  398.       
  399.      Some  users have encountered problems with compilers which claim to be
  400.      ANSI, but don't have fully ANSI preprocessors. Lines like:
  401.       
  402.           #ifdef (sizeof(int) == sizeof(short))
  403.       
  404.      often  in LIMITS.H are a dead giveaway. The ANSI standard specifically
  405.      prohibits  expressions  like this:  you can't  have casts,  sizeof, or
  406.      enumeration  constants  in a  #if expression.  It  is usually  done by
  407.      compilers that are trying to deduce the model you are using. Compliant
  408.      compilers define preprocessor symbols instead.
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.                                     Page - 7
  426.  
  427.  
  428.  
  429.                        USING CLINT FROM THE BORLAND IDE.
  430.                        ─────────────────────────────────
  431.       
  432.      You  can arrange to call  CLint from inside the  Borland IDE for Turbo
  433.      C++ 1.0 and upwards like this:
  434.       
  435.           From  the main  menu select Options,  then Transfer,  then Edit a
  436.           blank entry entering the following information:
  437.       
  438.                Program Title:  ~CLint current file
  439.       
  440.                Program Path:  C:\CLINT\CLINT.EXE
  441.       
  442.                Command Line:  $SAVE CUR $NOSWAP $CAP MSG(CLNT2MSG) -u -x -Z
  443.                               -D__TURBOC__ $EDNAME
  444.       
  445.           Then select Shift-F9 as the hotkey.
  446.       
  447.           Then  from the main menu select Options, then Transfer, then Edit
  448.           a blank entry entering the following information:
  449.       
  450.                Program Title:  C~Lint PROJECT.CLN
  451.       
  452.                Program Path:  C:\CLINT\CLINT.EXE
  453.       
  454.                Command Line:  $SAVE ALL $NOSWAP $CAP MSG(CLNT2MSG) -x -Z
  455.                               _D__TURBOC__ PROJECT.CLN
  456.       
  457.           Then select Shift-F10 as the hotkey.
  458.       
  459.      If  you installed CLint  in a different  directory, use that directory
  460.      name instead. If you told SETUP that you're using one of the supported
  461.      Borland  compilers, the  output filter  CLNT2MSG.EXE is  copied to the
  462.      compiler's BIN directory. The command line options for the IDE are:
  463.       
  464.           $SAVE CUR:     save the current file
  465.       
  466.           $NOSWAP:       don't switch screens
  467.       
  468.           $CAP:          capture CLint's output
  469.       
  470.           MSG(CLNT2MSG): pipe CLint's output through the filter
  471.       
  472.           -x, -u:        standard CLint switches
  473.       
  474.           -Z:            a special CLint switch for the IDE only
  475.       
  476.           $EDNAME:       the name of the current IDE file
  477.       
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.                                     Page - 8
  487.  
  488.  
  489.  
  490.      Unfortunately,  if  you have  existing project  files, you'll  need to
  491.      enter this information for each one.
  492.       
  493.      Shift-F9  runs CLint  against the  current file.  As it  uses the '-u'
  494.      option,  tests for  interaction with libraries  or other  files in the
  495.      project are suppressed. It is useful for rapid checks of a file whilst
  496.      being edited.
  497.       
  498.      To  use the second option, create  a file PROJECT.CLN for your project
  499.      containing a line for each source file in the project. You should also
  500.      place any project specific options using '-I', '-l', '-w' etc. one per
  501.      line as though they were being typed on the command line (see the next
  502.      section for details). This allows you to run CLint against your entire
  503.      project  by typing  Shift-F10, and  when CLint  finishes the  IDE will
  504.      correctly position the cursor against any errors or warnings detected.
  505.       
  506.      Once  you've created  PROJECT.CLN, it is  just as useful  from the DOS
  507.      command line - just type:
  508.       
  509.           CLINT
  510.       
  511.      as the special file PROJECT.CLN is used (if it exists) when CLint is
  512.      invoked with no file specifications. If you use MAKE, you may find it
  513.      convenient to add a target:
  514.       
  515.           clint:
  516.                clint -o report
  517.       
  518.      to  completely  check your  entire project,  and  leave the  report in
  519.      'REPORT'.
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.                                     Page - 9
  548.  
  549.  
  550.  
  551.                            THE COMMAND LINE OPTIONS.
  552.                            ─────────────────────────
  553.       
  554.      CLint  takes a number  of source file  names, possibly with wildcards,
  555.      and  analyses these sources. To control  the analysis and reporting, a
  556.      number   of  options  may  occur  on  the  command  line,  or  in  the
  557.      configuration  file CLINT.CFG, or  in files with  a '.CLN' extension -
  558.      PROJECT.CLN is special, if no files are specified and that file exists
  559.      it is used by default.
  560.       
  561.      The  filenames may be specified in full  or in part. Filenames with no
  562.      extension  are assumed to have the  extension '.C', failing which they
  563.      are  assumed to have the extension  '.CLN'. The files are inspected in
  564.      order  of  their  occurrence  on  the  command  line.  When  wild card
  565.      expansion occurs, the expanded names are ordered alphabetically.
  566.       
  567.      File  names with  no wildcards  and no  extension if  not matching any
  568.      files  with the extension '.C' have the extension '.CLN' appended, and
  569.      are then searched for in the current directory.
  570.       
  571.      Files  with the extension  '.CLN' are assumed  to contain command line
  572.      options  and filenames, one per line.  If filenames are present in the
  573.      file,  no wildcards  are permitted,  neither are  nested '.CLN' files.
  574.      Such  files are supported to allow the convenient specification of the
  575.      group of files comprising a project and the options they need. You may
  576.      have  any number of blank lines in  the file, and you can add comments
  577.      to any line by prefixing them with the '#' character.
  578.       
  579.      If  you use any version of the Borland IDE from Turbo C++ 1.0 upwards,
  580.      you  should  name such  files PROJECT.CLN  as described  earlier. Such
  581.      files  are read strictly  in left to right  order as encountered while
  582.      reading the command line. The effect is exactly as though each line of
  583.      the  '.CLN'  file is  inserted as  an argument  into the  command line
  584.      replacing  the '.CLN' filename argument. In subsequent discussion, all
  585.      comments regarding the precedence of command line options includes any
  586.      options found in '.CLN' files too.
  587.       
  588.      All  CLint options  begin with  a leading  '-' or  '/' character  - in
  589.      examples  below, we  use '-'. Except  as described  below, options are
  590.      case  insensitive unless the  C standard or  operating system requires
  591.      otherwise.
  592.       
  593.      Options  may occur in  any order on the  command line, intermixed with
  594.      file names. The options are read in the order:
  595.       
  596.           CLINT.CFG
  597.      and
  598.           command line left-to-right
  599.       
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.                                    Page - 10
  609.  
  610.  
  611.  
  612.      which  can  be important.  Options in  the  command line  may override
  613.      options in CLINT.CFG or earlier options in the command line.
  614.       
  615.      ──────────────────────────────────────────────────────────────────────
  616.      NOTE: CLint searches for CLINT.CFG first in the current directory, and
  617.      then  in the directory  specified in your  CLINT environment variable.
  618.      CLint issues no warnings if CLINT.CFG can't be found.
  619.      ──────────────────────────────────────────────────────────────────────
  620.       
  621.      Typing:
  622.       
  623.           CLINT /?
  624.       
  625.      produces a usage screen summarising the options.
  626.      ──────────────────────────────────────────────────────────────────────
  627.           -Ipath
  628.           -ipath
  629.       
  630.      where  'path' is a directory name.  Case may be important in directory
  631.      names  depending  on  the operating  system  you use.  It  specifies a
  632.      directory  to search for header  files. There may be  as many of these
  633.      options as required. The order of search for:
  634.       
  635.           #include "file"
  636.       
  637.      is
  638.       
  639.           current directory,
  640.           -I directories given on the command line,
  641.           -I directories given in CLINT.CFG.
  642.       
  643.      and for:
  644.       
  645.           #include <file>
  646.       
  647.      is
  648.       
  649.           -I directories given on the command line,
  650.           -I directories given in CLINT.CFG.
  651.       
  652.      You  can force  CLint to  forget all  the -I  options in  CLINT.CFG by
  653.      giving  '-I-' or '-i-' on the command  line prior to any other include
  654.      paths.
  655.       
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.                                    Page - 11
  670.  
  671.  
  672.  
  673.      ──────────────────────────────────────────────────────────────────────
  674.           -Dname
  675.           -dname
  676.           -Dname=value
  677.           -dname=value
  678.       
  679.      These  options define preprocessor macros.  Although the option letter
  680.      is  case insensitive,  the macro names  and values are  NOT. The first
  681.      form  defines a  macro with default  replacement text  '1'. The second
  682.      form  gives the replacement text explicitly. For your convenience, you
  683.      may append several definitions to an option with ';' like this:
  684.       
  685.           -Dname1;name2=4;name3=5;name4
  686.       
  687.      Note that the DOS command line can't handle options like:
  688.       
  689.           -Dname="1"
  690.       
  691.      properly.
  692.       
  693.      ──────────────────────────────────────────────────────────────────────
  694.           -Uname
  695.       
  696.      This  option  deletes a  preprocessor  macro. It  is  not an  error to
  697.      specify  a macro which was  not defined. It is  an error to attempt to
  698.      undefine:
  699.       
  700.           '__TIME__', '__DATE__', '__FILE__', or '__LINE__'.
  701.       
  702.      It can be used to undefine
  703.       
  704.           '__CLINT__' or '__DOS__'
  705.       
  706.      or  any  symbols defined  in CLINT.CFG.  As with  '-D' you  can append
  707.      several names with ';' like this:
  708.       
  709.           -Uname1;name2
  710.       
  711.      The order of '-D' and '-U' is important - you may only undefine macros
  712.      whose definition precedes the '-U' option.
  713.       
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.                                    Page - 12
  731.  
  732.  
  733.  
  734.      ──────────────────────────────────────────────────────────────────────
  735.           -o file
  736.           -O file
  737.           -ofile
  738.           -Ofile
  739.       
  740.      This option specifies a file to receive CLint's output. By default the
  741.      output  is written  to 'stderr'. If  you use this  option, CLint still
  742.      writes  the source file name it is  working on to 'stderr' to show you
  743.      how  it is proceeding.  If more than  one of these  options occur, the
  744.      rightmost one is used.
  745.       
  746.      ──────────────────────────────────────────────────────────────────────
  747.           -e0
  748.       
  749.      By  default CLint stops reading a file  if 15 errors are produced, and
  750.      proceeds  to the next file with the  message 'Too many errors'. If you
  751.      use this option the limit is removed.
  752.       
  753.      ──────────────────────────────────────────────────────────────────────
  754.           -eNNN
  755.       
  756.      Use  this option to specify  the error limit you  need. The default is
  757.      15.  If this  option and  '-e0' occur  together, the  rightmost one is
  758.      obeyed.
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.                                    Page - 13
  792.  
  793.  
  794.  
  795.                                     WARNINGS
  796.                                     ────────
  797.       
  798.      ──────────────────────────────────────────────────────────────────────
  799.           -w0
  800.           -W0
  801.       
  802.      By  default, CLint stops  reading a file if  60 warnings are produced,
  803.      and proceeds to the next file with the message 'Too many warnings'. If
  804.      you use this option the limit is removed.
  805.       
  806.      ──────────────────────────────────────────────────────────────────────
  807.           -wNNN
  808.       
  809.      Use  this option to specify the warning limit you need. The default is
  810.      60.  If this  option and  '-w0' occur  together, the  rightmost one is
  811.      obeyed.
  812.       
  813.      ──────────────────────────────────────────────────────────────────────
  814.           -wall
  815.       
  816.      A  number of CLint's  warnings are optional, and  OFF by default. This
  817.      turns all warnings on.
  818.       
  819.      ──────────────────────────────────────────────────────────────────────
  820.           -w-all
  821.       
  822.      This turns all warnings off. It may usefully occur in CLINT.CFG when
  823.      followed by '-wxxx' options to turn on only those warnings you need.
  824.       
  825.      ──────────────────────────────────────────────────────────────────────
  826.           -wxxx
  827.       
  828.      Turn the specified warning on.
  829.       
  830.      ──────────────────────────────────────────────────────────────────────
  831.           -w-xxx
  832.       
  833.      Turn the specified warning off.
  834.       
  835.  
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.                                    Page - 14
  853.  
  854.  
  855.  
  856.      ──────────────────────────────────────────────────────────────────────
  857.       
  858.      This is the complete list of warning switches. Any of them may be used
  859.      in  CLINT.CFG or  on the  command line.  Unless changed  by CLINT.CFG,
  860.      those switches marked below with '*' are enabled by default.
  861.       
  862.       *wcom         warn of nested comments
  863.        webr         else needs '{'
  864.        wfbr         for needs '{'
  865.        wibr         if needs '{'
  866.        wwbr         while needs '{'
  867.        wspc         advise on spacing
  868.        wlfb         warn of functions longer than 120 lines
  869.        wlfbNNN      warn of functions greater than NNN lines long
  870.        wtyb         typedefing primitive types
  871.       *wtye         warn of typedefing enums
  872.       *wtyg         warn of general (complex) typedefs
  873.       *wtyp         warn of typedefing pointer types
  874.       *wtys         warn of typedefed structs with lower case names
  875.        wtysU        typedefed structs with names not fully in upper case
  876.       *wstv         warn of passed/returned structs (by value)
  877.       *wcon         warn of constant conditions
  878.       *whdr         show warnings in user header files
  879.        wshd         show warnings in system header files
  880.       *wprn         warn of misuse of printf (sprintf, fprintf, etc)
  881.       *wenu         warn of enum misuse
  882.       *wtri         warn about trigraphs
  883.       *winc         warn of multiply included header files
  884.       *wiag         warn of auto aggregate initialisation
  885.       *wunr         warn of unreachable code
  886.       *welb         warn of empty loop bodies
  887.       *wcil         long constant needs 'L'
  888.       *wsig         warn of loss of significance with longs
  889.        wsig+        warn of loss of significance with any type
  890.       *wmxp         warn of mixed pointers to signed/unsigned char
  891.       *wenu         warn of enum misuse
  892.       *wnus         warn of variables defined but not used
  893.       *wpro         warn of function use without a prototype
  894.       *wret         warn of return misuse
  895.       *wlib         warn of library symbol redefinition
  896.       *wlnf         warn of bit fields longer than 16 bits
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.                                    Page - 15
  914.  
  915.  
  916.  
  917.                                 SPECIAL OPTIONS
  918.                                 ───────────────
  919.       
  920.           -L file
  921.       
  922.      This  important option  instructs CLint  to change  it's behaviour, in
  923.      that  it knows that the source files will be headers not program text.
  924.      Each  prototype or external declaration in the source files is written
  925.      to  the 'file' in  a form to be  later read into  CLint using the '-l'
  926.      option. This file is needed if CLint is to check your usage of library
  927.      functions and variables properly.
  928.       
  929.      Note  that many errors will  be reported if this  option is applied to
  930.      program  source, and that the  '-L' MUST be upper  case. The file name
  931.      case is only important if your operating system requires.
  932.       
  933.      ──────────────────────────────────────────────────────────────────────
  934.           -lfile
  935.       
  936.      This  option  instructs CLint  to  read a  definition  file previously
  937.      prepared  with  the '-L'  option above  after  reading all  the source
  938.      files. Declarations and usage in your source files will be compared to
  939.      those recorded in the definition file, and may result in the warning:
  940.       
  941.           Warning: 'name' in file(NNN) hides a library symbol in 'file'
  942.       
  943.      If this happens, you have defined a function or variable which is also
  944.      defined in a library. C allows this, but in some cases it may be a bug
  945.      in  your  code.  You may  suppress  these warnings  with  the '-w-lib'
  946.      option.
  947.       
  948.      If  you don't use the '-l' option for each library you use, CLint will
  949.      complain  about a  long list of  functions and variables  used but not
  950.      defined  (exactly as  the linker  would if you  failed to  link in the
  951.      library at link time).
  952.       
  953.      The  '-l'  option is  used differently  in CLINT.CFG:  you must  use a
  954.      directory name. For example, suppose that you place all the definition
  955.      files you created with the '-L' option above in
  956.       
  957.           \CLINT\MYLIBS
  958.       
  959.      If you want CLint to check usage in ALIB in this directory, you place:
  960.       
  961.           -l\clint\mylibs
  962.       
  963.      in CLINT.CFG, and on the command line use:
  964.       
  965.           -lalib
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.                                    Page - 16
  975.  
  976.  
  977.  
  978.      ──────────────────────────────────────────────────────────────────────
  979.           -E
  980.       
  981.      Use  CLint  as  an ANSI  C  pre-processor.  The output  is  written to
  982.      'stdout'  and may  be redirected,  or the '-o'  option may  be used to
  983.      write  the output  to any  named file.  If wild  cards are  used, each
  984.      source file is pre-processed in turn resulting in all output appearing
  985.      in the same file.
  986.       
  987.      ──────────────────────────────────────────────────────────────────────
  988.           -u
  989.       
  990.      This  switch  informs CLint  that the  files  given are  not complete,
  991.      either  they are  a library or  only part  of a program.  In any case,
  992.      complaints about symbols used but not defined and defined but not used
  993.      are suppressed.
  994.       
  995.      ──────────────────────────────────────────────────────────────────────
  996.           -T
  997.       
  998.      This  switch tells Clint  to detect functions  and variables which are
  999.      only  used in the  file in which  they are declared.  It then prints a
  1000.      warning  about  all  such  variables, observing  that  they  should be
  1001.      declared 'static'.
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007.  
  1008.  
  1009.  
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.                                    Page - 17
  1036.  
  1037.  
  1038.  
  1039.                               CONTROL OF TYPEDEFS
  1040.                               ───────────────────
  1041.       
  1042.      'typedef'  is often  misused. You  can control  the way  CLint reports
  1043.      these misuses in a number of ways:
  1044.       
  1045.      ──────────────────────────────────────────────────────────────────────
  1046.      -wtye enables reports of typedefing enums, for example:
  1047.       
  1048.           typedef enum { A, B} THING;
  1049.       
  1050.      provokes   the  report:  "typedefed  enum  as  'THING'".  We  consider
  1051.      typedefing  enums to be  poor practise as  discussed elsewhere, except
  1052.      for the example given below.
  1053.       
  1054.      ──────────────────────────────────────────────────────────────────────
  1055.      -wtys  enables reports about  typedefing structs or  unions without an
  1056.      initial  capital letter in the name, -wtysU enables reports about this
  1057.      without  the name being all upper case.  We consider that at least the
  1058.      name should start with a capital letter, preferably all upper case.
  1059.       
  1060.      ──────────────────────────────────────────────────────────────────────
  1061.      -wtyp enables reports about typedefing pointer types. We consider this
  1062.      to be one of the major abuses of typedef.
  1063.       
  1064.      ──────────────────────────────────────────────────────────────────────
  1065.      -wtyg  enables reports about strange typedefs - for example typedefing
  1066.      an  array. We  produce this message  for any typedef  which is complex
  1067.      (not  a  primitive type,  struct,  union, enum,  or  pointer). Complex
  1068.      typedefs   are  in  our  opinion  dangerous  as  they  hide  too  much
  1069.      information.
  1070.       
  1071.      ──────────────────────────────────────────────────────────────────────
  1072.      -wtyb  enables reports about typedefing  primitive types such as 'int'
  1073.      with names that are not all lower case. There are occasions where this
  1074.      is  useful, but  we believe that  for clarity the  typedef name should
  1075.      always be lower case.
  1076.       
  1077.      CLint  already knows about standard ANSI names which are typedefed, as
  1078.      follows:
  1079.       
  1080.           div_t, ldiv_t, size_t, wchar_t, clock_t, time_t,
  1081.           fpos_t, jmp_buf, va_list, tm,
  1082.       
  1083.      and will never complain about their definitions.
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.                                    Page - 18
  1097.  
  1098.  
  1099.  
  1100.                               DISCUSSION SECTIONS
  1101.                               ───────────────────
  1102.       
  1103.      We  believe that  C programs  should be  understandable, maintainable,
  1104.      portable, and above all efficient. CLint was designed to assist in the
  1105.      achievement  of these goals. CLint  produces several reports which can
  1106.      help  you write code  meeting these objectives.  We discuss several of
  1107.      the reports which may occur.
  1108.       
  1109.      1. EFFICIENCY
  1110.      ─────────────
  1111.       
  1112.      ──────────────────────────────────────────────────────────────────────
  1113.      auto aggregate initialisation
  1114.       
  1115.           An  'aggregate'  is  any  structure,  union  or  array  -  i.e. a
  1116.           collection  of more primitive objects.  All compilers use code to
  1117.           initialise  'auto'  objects.  Where these  objects  are primitive
  1118.           types, the code is equivalent to assignment.
  1119.       
  1120.           Where  the object is a 'struct', 'union', or array, the compilers
  1121.           generate  a static unnamed object of the same type and initialise
  1122.           that  - and then generate code to copy this hidden object to your
  1123.           object.
  1124.       
  1125.           You  can save  code and  speed up  your program  by declaring the
  1126.           object   'static'  which   avoids  the  copy   operation  as  the
  1127.           initialisation  is performed once at compile time. This will only
  1128.           work  if you never  modify the object! If  you do, then carefully
  1129.           examine  the logic of  your code - it  is almost never necessary,
  1130.           and often confusing. A common case is:
  1131.       
  1132.                void f()
  1133.                {
  1134.                     char string[] = "a string ....";
  1135.                }
  1136.       
  1137.           where  if 'string' is  not modified it should  be static. You can
  1138.           disable this warning with -w-iag.
  1139.  
  1140.  
  1141.  
  1142.  
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  
  1157.                                    Page - 19
  1158.  
  1159.  
  1160.  
  1161.      ──────────────────────────────────────────────────────────────────────
  1162.      struct/union passed by value
  1163.      struct/union value returned
  1164.       
  1165.           Both  these  cases  cause  a significant  amount  of  code  to be
  1166.           generated,  and stack space  usage equivalent to  the size of the
  1167.           object.  When you  pass a  structure value,  the entire  value is
  1168.           pushed  on the stack. When you  return a structure, space for the
  1169.           return value is reserved on the stack, and in normal cases copied
  1170.           from the stack to the destination, for example:
  1171.       
  1172.                struct x {
  1173.                     ......
  1174.                };
  1175.       
  1176.                struct x f(void)
  1177.                {
  1178.                     struct x y;
  1179.       
  1180.                     ......
  1181.                     return y;
  1182.                }
  1183.       
  1184.           This  typical  code  skeleton  copies the  value  of  'y'  to the
  1185.           reserved  space on the stack, and (assuming you use the result by
  1186.           assignment)  copies that value  to the destination!  If you don't
  1187.           want these warnings, use -w-stv.
  1188.       
  1189.      ──────────────────────────────────────────────────────────────────────
  1190.      '<name>' not used
  1191.      static '<name>' not used
  1192.      '<name>' assigned to but not used
  1193.      static '<name>' assigned to but not used
  1194.      argument '<name>' not used
  1195.       
  1196.           These  all indicate problems with the  program logic - often they
  1197.           are  a  result  of  code  changes  which  cause  previously  used
  1198.           variables  to become unused. Sometimes they indicate a real bug -
  1199.           you  assigned a value  for a reason,  but then that  value is not
  1200.           used.  However they  arise, they should  be cleared -  if only to
  1201.           reduce the size of the program.
  1202.       
  1203.           In  the case of "argument 'x' not used" this may be intentional -
  1204.           you can silence CLint by placing:
  1205.       
  1206.                #pragma argsused
  1207.       
  1208.           ahead of the function declaration. This clearly announces what is
  1209.           going on to any people reading the code too.
  1210.  
  1211.  
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.                                    Page - 20
  1219.  
  1220.  
  1221.  
  1222.      ──────────────────────────────────────────────────────────────────────
  1223.      label '<name>' unused
  1224.       
  1225.           Most  compilers assume when they see  a label that control may be
  1226.           transferred  to  a label  by  'goto', and  therefore  discard the
  1227.           values  of any registers they may be remembering. A label that is
  1228.           not used will usually not be detected as such, and will cause the
  1229.           same  action.  This  can  result  in  larger  slower  code  being
  1230.           generated immediately following such a label.
  1231.       
  1232.      2. CODING STYLE
  1233.      ───────────────
  1234.       
  1235.      ──────────────────────────────────────────────────────────────────────
  1236.      statement after 'for' should have '{'
  1237.      statement after 'while' should have '{'
  1238.      statement after 'do' should have '{'
  1239.      statement after 'if' should have '{'
  1240.      statement after 'else' should have '{'
  1241.       
  1242.           Any of these not followed by a keyword, as for example:
  1243.       
  1244.                if (x > 5)
  1245.                     ++i;
  1246.       
  1247.           should be fully braced like this:
  1248.       
  1249.                if (x < 5) {
  1250.                     ++i;
  1251.                }
  1252.       
  1253.           If  you agree  with us,  any of  these may  be enabled  by -wfbr,
  1254.           -wwbr, -wibr, -webr.
  1255.       
  1256.      ──────────────────────────────────────────────────────────────────────
  1257.      ' ' advised after '='
  1258.      ' ' advised after ','
  1259.      ' ' advised after ';'
  1260.      ' ' advised after ':'
  1261.       
  1262.           Some  spacing  styles  are  hard to  read.  We  believe  that all
  1263.           operators  should have white  space either side,  but this is too
  1264.           draconian, so we object to things like:
  1265.       
  1266.                a=1,b=2;f(3,a);
  1267.       
  1268.           which will provoke 5 complaints. It should be written as:
  1269.       
  1270.                a = 1, b = 2; f(3, a);
  1271.       
  1272.      If you want this checking, enable it with -wspc.
  1273.  
  1274.  
  1275.  
  1276.  
  1277.  
  1278.  
  1279.                                    Page - 21
  1280.  
  1281.  
  1282.  
  1283.      ──────────────────────────────────────────────────────────────────────
  1284.      ' ' advised after '<keyword>'
  1285.       
  1286.           We  believe  that  many  people  reading  code  use  visual clues
  1287.           extensively.  One of the clues often  used is function calls have
  1288.           the  form 'name(...)'. Some  programmers have a  habit of writing
  1289.           language clauses as though they were function calls, like:
  1290.       
  1291.                if(j == 0)
  1292.       
  1293.           At  first glance, this is enough like a function call to at least
  1294.           arrest the eye. This is also enabled by -wspc.
  1295.            
  1296.       
  1297.      3. USE OF TYPEDEF.
  1298.      ──────────────────
  1299.       
  1300.      ──────────────────────────────────────────────────────────────────────
  1301.      typedefed enum as '<name'>
  1302.      typedefed struct/union as '<name>' - use initial capital
  1303.      typedefed a pointer as '<name>'
  1304.      typedefed 'unsigned char' as '<name>' - use lower case
  1305.       
  1306.           We  consider typedef misuse  to be one of  the major crimes often
  1307.           committed  with  C. Some  extremely obscure  code can  occur when
  1308.           typedefs  are used, and  if the declaration is  in a header file,
  1309.           considerable  time may be needed to discover what the code really
  1310.           means - for example, given:
  1311.       
  1312.                #include "junk.h"
  1313.       
  1314.                void f()
  1315.                {
  1316.                     garbage x;
  1317.       
  1318.                     ........
  1319.                }
  1320.       
  1321.           what is 'x'? We propose some rules for the use of typedef to make
  1322.           it at least possible to get some hints:
  1323.       
  1324.                1) When typedefing unions or structs, always have an initial
  1325.                capital letter in the name - or capitalise the entire name.
  1326.       
  1327.                2) Never typedef an enumeration - use 'enum thing x' instead
  1328.                which clearly announces to the reader what is going on.
  1329.       
  1330.                3)  Never typedef pointer types - the presence of the '*' in
  1331.                the declaration is a valuable clue to understanding.
  1332.       
  1333.                4) When typedefing a primitive type, always use a lower case
  1334.                name,  the reader  can then be  assured that  all lower case
  1335.                type names are really simple objects like 'int'.
  1336.       
  1337.  
  1338.  
  1339.  
  1340.                                    Page - 22
  1341.  
  1342.  
  1343.  
  1344.           These  objections can  be enabled  if you  agree with  us: -wtye,
  1345.           -wtys, -wtyp, -wtyb.
  1346.       
  1347.      4. POTENTIALLY SERIOUS BUGS
  1348.      ───────────────────────────
  1349.       
  1350.      There  are many potential  bugs which CLint warns  about. Some of them
  1351.      can lead to extremely obscure problems. The most important are:
  1352.       
  1353.      ──────────────────────────────────────────────────────────────────────
  1354.      '<name>' possibly used before definition
  1355.       
  1356.                You will recall that 'auto' and 'register' objects which are
  1357.                not  the arguments  of functions have  undefined values (for
  1358.                this  read 'whatever was on the  stack before the call'). If
  1359.                you  refer to the value of such  an object before a value is
  1360.                assigned to it you are guaranteed to get junk. Sometimes the
  1361.                message may be inappropriate, as in:
  1362.       
  1363.                     struct x {
  1364.                          struct x *next;
  1365.                          ......
  1366.                     } *head, *p, *q;
  1367.       
  1368.      ──>            for (p = head; p; p = q) {
  1369.                          q = p->next;
  1370.                     }
  1371.       
  1372.                This  provokes "'q' possibly used  before definition" at the
  1373.                line  marked with the arrow - but  we can see that 'q' is in
  1374.                fact  assigned before it's  value is required  in the 'for'.
  1375.                Almost  any other occurrence of this bug is a genuine error,
  1376.                and   it  is  worth  clearing  this  non-error  occasion  by
  1377.                initialising 'q' to NULL anyway.
  1378.      ──────────────────────────────────────────────────────────────────────
  1379.      "evaluation order undefined"
  1380.       
  1381.                The standard clearly states that in a statement like:
  1382.       
  1383.                     int a[10], i;
  1384.       
  1385.                     a[i] = ++i;
  1386.       
  1387.                that  the meaning of the  statement is undefined because the
  1388.                compiler   writer  is   free  to   evaluate  the  expression
  1389.                components in any order that is convenient - to the compiler
  1390.                writer!  In cases like  this, he may  decide to evaluate the
  1391.                address  of the  array element  before evaluating  the right
  1392.                hand side - or he may not.
  1393.       
  1394.  
  1395.  
  1396.  
  1397.  
  1398.  
  1399.  
  1400.  
  1401.                                    Page - 23
  1402.  
  1403.  
  1404.  
  1405.                Similar  problems arise with  any operator which  has a side
  1406.                effect,  and CLint takes some care  to check them all. It is
  1407.                also  careful that when operators  whose evaluation order is
  1408.                defined  by the  standard are  used, ('||',  '&&', '?', ',')
  1409.                that improper complaints don't occur.
  1410.                 
  1411.                A  particular  trap with  optimising  compilers is  that the
  1412.                order of evaluation of function arguments is undefined, so:
  1413.                 
  1414.                     f(a[i], i++);
  1415.                 
  1416.                provokes this complaint too.
  1417.       
  1418.      ──────────────────────────────────────────────────────────────────────
  1419.      ambiguous operators need parentheses
  1420.       
  1421.                This occurs if any of the operators '||', '&&', '|', '&', or
  1422.                '^'  are  adjacent and  different  in an  expression without
  1423.                parentheses round one of them. For example:
  1424.       
  1425.                     if (flag && test1 || test2) ....
  1426.       
  1427.                is true if 'flag && test' or 'test2'. This occurred in CLint
  1428.                itself  - in several places! -  before we fixed it. What was
  1429.                meant was of course:
  1430.       
  1431.                     if (flag && (test1 || test2)) ....
  1432.       
  1433.                This  can cause no end of  grief, because most people forget
  1434.                the relative precedences of these operators.
  1435.       
  1436.      ──────────────────────────────────────────────────────────────────────
  1437.      printf: ....
  1438.       
  1439.                There  are a  series of  possible errors  that can  be given
  1440.                concerning  the use  of 'printf',  'fprintf', and 'sprintf'.
  1441.                All  calls to these library functions are tested argument by
  1442.                argument   against  the  ANSI  standard  for  the  supported
  1443.                conversions.  Each  '%'  conversion is  checked  against the
  1444.                corresponding  argument to be of  the correct type. This can
  1445.                catch  a  surprising number  of  bugs in  apparently working
  1446.                programs.
  1447.       
  1448.                You  can also define  functions of your  own which work like
  1449.                'printf()'. You should then use the -FNname switch to inform
  1450.                CLint  of these functions  so that it can  check your use of
  1451.                these functions.
  1452.       
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.  
  1461.  
  1462.                                    Page - 24
  1463.  
  1464.  
  1465.  
  1466.      ──────────────────────────────────────────────────────────────────────
  1467.      unreachable code
  1468.       
  1469.                This may occur due to any number of logical problems. It can
  1470.                also  be  caused by  providing  a 'return  x'  which Borland
  1471.                compilers  sometimes incorrectly  insists on  at the  end of
  1472.                functions.  In cases where you  know the statement concerned
  1473.                can't be reached, precede the offending statement with:
  1474.       
  1475.                     #pragma notreached
  1476.       
  1477.                which  will  silence  CLint, but  not  unfortunately Borland
  1478.                compilers.
  1479.       
  1480.      ──────────────────────────────────────────────────────────────────────
  1481.      value should be returned
  1482.      both return and return of a value
  1483.       
  1484.                These  are often a hold-over from pre-ANSI C code. You would
  1485.                often write:
  1486.       
  1487.                     func()
  1488.                     {
  1489.                          .....
  1490.                     }
  1491.       
  1492.                where under ANSI you should write:
  1493.       
  1494.                     void func(void)
  1495.                     {
  1496.                          .....
  1497.                     }
  1498.       
  1499.                The second case is more worthy of attention. A number of so-
  1500.                called working programs exhibit this one - it can be a nasty
  1501.                trap.  Often,  the program  will work  - under  a particular
  1502.                compiler  - because the value in the return register left by
  1503.                a  prior expression just happened  to be the value required!
  1504.                You should always fix this.
  1505.       
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.                                    Page - 25
  1524.